Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

Good catch! I've updated the OSC pattern to be more general.

Before: Matched only OSC codes 10, 11, 4
After: Matches any OSC sequence ending with ;? (the query marker)

The new pattern: ESC ] Ps [;param] ;? TERMINATOR

This catches all OSC queries:

• ✅ OSC 10/11 (fg/bg color)
• ✅ OSC 4 (palette)
• ✅ OSC 12 (cursor color)
• ✅ OSC 17 (highlight background)
• ✅ Any future OSC query types

While preserving SET operations:

• ✅ OSC 0 (window title) - no ;? = preserved
• ✅ OSC 8 (hyperlinks) - no ;? = preserved
• ✅ OSC 7 (working directory) - no ;? = preserved

Added 5 new tests to verify the behavior. See commit a499579.

📁 PR Artifacts Notice

This PR contains a .pr/ directory with PR-specific documents. This directory will be automatically removed when the PR is approved.

For fork PRs: Manual removal is required before merging.

Manual Testing Instructions

A real-world test script is available in .pr/test_real_world.py to verify the fix works correctly.

How to Run

# Clone and checkout the branch
git fetch origin fix/terminal-escape-filter-minimal
git checkout fix/terminal-escape-filter-minimal

# Run the test (uses All-Hands LLM proxy)
LLM_BASE_URL="https://llm-proxy.eval.all-hands.dev" LLM_API_KEY="$LLM_API_KEY" \
    uv run python .pr/test_real_world.py

What the Test Does

1. Creates an agent with the terminal tool
2. Asks it to run gh pr list --repo OpenHands/openhands --limit 3
3. The gh command sends terminal query sequences (DSR, OSC) as part of its spinner UI
4. With the fix, these queries are filtered from the captured output

Success Criteria

✅ Pass if:

• NO visible escape codes like ^[[38;1R or rgb:30fb/3708/41af in the output
• NO garbage appears on your shell prompt after the script exits
• Colors from gh output are still visible (formatting preserved)

❌ Fail if:

• You see raw escape sequences in the terminal output
• Garbage characters appear after the script completes

Without the Fix (for comparison)

To see the problem on main:

git checkout main
LLM_BASE_URL="https://llm-proxy.eval.all-hands.dev" LLM_API_KEY="$LLM_API_KEY" \
    uv run python .pr/test_real_world.py

You should see escape code garbage like ^[[6n or ]11;? in the output.

I have confirmed that this solution works. Note that there is a change in what the agent displays. Since we filter out OSC queries, the cli does not render the gh spinner. I think this an acceptable limitation. (Note that we aren't preventing the spinner from displaying, but when gh doesn't get back terminal query results, it elects not to display the spinner.)

Why the gh Spinner Doesn't Render Properly

The spinner animation in gh (and similar CLI tools) relies on terminal query sequences to function correctly. Here's why:
How Spinners Work

1. Query cursor position: The spinner sends \x1b[6n (DSR) to ask "where is my cursor?"
2. Receive response: The terminal responds with \x1b[row;colR
3. Overwrite in place: Using the cursor position, the spinner moves back and overwrites itself with the next frame (⣾ → ⣽ → ⣻ → etc.)

What Our Filter Does

We filter out DSR queries (\x1b[6n) from the captured output because when they're displayed to the user's terminal, that terminal responds - and the response becomes visible garbage.

The Consequence

Without the cursor position query reaching the terminal:

• The spinner never learns where it is
• It can't move back to overwrite itself
• Each spinner frame may appear on a new line, or the spinner may not animate at all

Why This Is Acceptable

1. The command still works - gh pr list executes correctly and returns results
2. Actual output is preserved - The PR list, colors, and formatting are intact
3. Agent context - Spinners are for human feedback during waits; the agent doesn't need visual progress indicators
4. The alternative is worse - Without filtering, you get ^[[6n^[[38;1R garbage polluting the output

Why Filter the Query, Not the Response?

The Response Problem

When a terminal query like \x1b[6n is displayed, the user's terminal:

1. Processes the query
2. Writes its response to stdin (e.g., \x1b[38;1R)

Filtering the response would require:

1. Monitoring stdin continuously - Responses arrive asynchronously, potentially long after we've returned output to the agent. We'd need to constantly drain stdin throughout the entire session.
2. Distinguishing responses from user input - If a user types while the agent is running, their keystrokes arrive on stdin too. How do we know \x1b[A is a terminal response vs. the user pressing the up arrow? We risk eating legitimate input.
3. Racing against echo - By the time the response arrives on stdin, the terminal may have already echoed it to the display. The visible garbage (^[[38;1R) appears because the terminal echoes the response before we can intercept it. Filtering stdin doesn't prevent the visual pollution - the damage is already done.
4. Complex terminal mode manipulation - Reliably reading stdin without blocking, while preserving terminal state, while not corrupting user input, across different platforms... this is the path the original PR fix(terminal): filter terminal query sequences from captured output #2245 went down with flush_stdin() - 700+ lines of complexity and it did not work reliably without the OSC filtering.

Why Filtering Queries Is Better

1. Single point of control - Filter in _get_command_output() before output is returned
2. No response is ever generated - If the query never reaches the display terminal, there's nothing to clean up
3. No stdin complexity - No terminal modes, no race conditions, no risk of eating user input
4. Deterministic and testable - Simple regex on captured output

I think this is ready except that should probably test the CLI built against this version of the SDK to ensure that our approach here doesn't interfere with the TUI.

Perhaps the best course is to open a PR that will build the CI against this branch of the SDK and recruit some users to use it for a day or two.

It looks like testing this in the CLI is blocked until breaking change in #2133 is dealt with in the CLI unless we rebase this fix branch on v1.11.5.

This PR was merged and should address the blocker on testing with OpenHands-CLI OpenHands/OpenHands-CLI#587

@OpenHands Do a /codereview-roasted on this PR. Publish your review feedback as review on the PR, using your appropriate event in gh api. (not a comment, a review, you are allowed to review)

I'm on it! enyst can track my progress at all-hands.dev

Final summary:

• Reviewed PR fix(terminal): filter terminal query sequences from captured output #2334 against main, the PR description, and linked issue #2244.
• Submitted a GitHub PR review using the proper COMMENT review event via gh api (not a regular comment).
• Left two substantive inline concerns:
  1. the fix only sanitizes output in TerminalSession, so it does not fully cover the SDK-side leakage described in #2244
  2. the filter is stateless, so escape sequences split across incremental output chunks can still leak through

Checklist:

• Performed a roasted code review of the PR
• Published feedback as a review, not a comment
• Focused on important correctness issues only
• Made no code changes
• No extraneous local modifications to push

Because I did not change repository files, there was nothing to push to the remote branch.

[Automatic Post]: It has been a while since there was any activity on this PR. @jpshackelford, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[Automatic Post]: This PR seems to be currently waiting for review. @xingyaoww, could you please take a look when you have a chance?